Mac Magazin/MacEasy 19/Mac Magazin and MacEasy Magazine CD - Issue 19.iso/Grafik & Text & Film/bigeyedemo folder/BEman (text)

Text File | 1996-02-05 | 82KB | 1,561 lines

introduction

BigEye is a computer program designed to take realtime video information and
convert it into midi messages. It runs on  any Macintosh computer running system
7 or later, QuickTime 1.6 and the Apple Midi Manager. Available in both 68000
Macintosh and Power PC versions, it supports all QuickTime compatible video
digitizers, including serial cameras like the Connectix QuickCam, making it usable
for PowerBooks and other non-AV Macintoshes. It is also  possible to use
prerecorded QuickTime movies as a video input source.

The user configures the program to extract objects of interest, based on colour,
brightness and size. These objects are tracked (up to 16 simultaneously) and their
position is checked against a user-defined series of ‘hot zones’.  These ‘hot zones’
are drawn by the user and are grouped in ‘screens’.

Objects and ‘hot zones’ interact in three distinct ways:  a zone sees a new
object, a zone sees an old object moving, and a zone sees an object disappear.
Each of these three ‘events’ can generate midi or cause internal program
parameters to change. A simple example: the new event causes a note to be
switched on, a move event causes a midi pitchbend and a disappear event causes
the note to be switched off.

To specify the midi messages to be sent out the program provides two distinct
modes: a simple mode in which the user can specify midi parameters and screen
changes; and a powerful, complete scripting language that includes a real time
scheduler, conditionals and loops. In the simpler environment one can quickly link
to midi most of the causing object’s parameters, such as position, speed and size.
In scripting mode one has many more parameters available.
BigEye provides for 16 independent ‘channels’ which can analyze the incoming
image in different ways, allowing, for instance, green objects to act completely
differently from objects of other colours.

Applications for BigEye are to be found in the arts, entertainment and museum
world. One can think of dancers/performers ‘playing’ BigEye as an instrument,
interactive museum exhibits, video ‘auto scoring’, video games accompaniment,
etc. With suitable camera attachments wild applications include endoscopic music,
performing bacteria (through a microscope). Also, with midi equipment other than
sound synthesizers being widely available, sound mixing, light mixing, slide projector
control are a few of the options.

Please communicate your experiences.
aug. 1995, Tom Demeyer
hardware and software setup

Due to the high demand on the computer’s processing resources it is advisable
to use as fast a computer as possible. Typically achievable frame rates range from
2 frames per second on a PowerBook Duo 210 to 14 frames per second on a
PPC 7100/66. (With the use of more capable video digitizer boards these rates
could go  up quite dramatically.)
BigEye has been tested so far (May 1995) only with the AV built-in digitizers
(quadra 840AV, powermacs 6100 and 7100 and performa 630), and the
Connectix Quickcam. The program should run on any QuickTime compatible
digitizer, though. Please communicate your experiences.
Both Quicktime 1.6 or later and the Apple Midi Manager should be on your
system, QuickTime and Apple Midi Manager in your extensions folder and the Midi
Driver in the system folder.
Hardware setup is simple, a video source goes into the AV card’s video input
(when you only use QuickTime clips, this is of course not necessary), and a midi
interface plugs into you modem or printer port. BigEye currently ignores midi
input, so a single midi cable from the computer to your midi equipment is enough.

One aspect of your ‘hardware’ setup is of extreme importance. When you are
working with a camera as an input source, the lighting conditions are a very
important part of a previously practiced setup. The light intensity and the colour of
the light is what BigEye ‘feeds’ on. Unlike the human eye, BigEye works with
absolute colours and with absolute intensities. What you may perceive as identical
lighting conditions may in actual fact be completely different. Be prepared the
reconfigure your colour tables and your threshold settings when you move from
location to location.


---------------------------------------------------------------------------------
BASIC STRUCTURE OF THE PROGRAM
---------------------------------------------------------------------------------

The basic premise of BigEye is to interpret a video image and to convert it into
midi information according to specifications set up by the user. Interpretation is
done on a frame by frame basis, the program retains knowledge of previous
frames, so the system is able to interpret movement. The frame rate is
determined by the amount of information in the image, the processing required to
extract this information and, most of all by the power of the computer.
The first step is for the user to specify which objects in the incoming video
image are to be looked at and which parts of the image are to be ignored. This is
done on the basis of the brightness and/or colour attributes of elements in the
image (see image filters, p ). When the user has thus singled out the objects of
interest, the next step is to define the ‘hot zones’ or ‘regions’ with which the
objects will interact. This is done simply by drawing on the screen using the
mouse; a set of simple drawing tools is provided in the ‘region edit window’ for this
purpose.
The next step is to define what should happen when an object interacts with a
region. Here BigEye provides for two levels of sophistication; a ‘simple mode’,
where the user selects midi commands using pop-up menus and scrolling
‘numericals’, and the more powerful scripting facility where the user writes scripts
describing actions to be taken when an object interacts with a region.
Interaction between objects and regions can take three distinct forms; whether
in scripting mode or in ‘simple’ mode, interaction is taking place through what are
called ‘new’, ‘move’ and ‘gone’ messages.
A ‘new’ message is processed by a region when it sees an object appear within
its bounds, the objects can be an existing one, which is at that moment sliding
from outside the region’s bounds to somewhere within, or it can be a completely
new object, materializing within the region. In both cases the region triggers either
its ‘new-script’ or performs the ‘new’ action list defined in ‘simple’ mode.
A ‘move’ message is processed when an existing object, already within the
region’s bounds, is moving around (within its bounds). Different scripts or action
lists can be associated with this ‘move’ message.
A ‘gone’ message is acted upon by a region when a previously ‘newed’ object
either moves outside the region’s perimeter, or disappears from the screen
altogether.
BigEye  provides for multiple ‘channels’ (separate data streams, based on
differently coloured objects, for instance), multiple screens of region definitions and
multiple colour tables.
Here is a simple step by step example to illustrate the basics just described:

•Start BigEye, and from the ‘Source’ menu select ‘animation’. This selects as
input to the program a simple animation of some coloured balls, to be used for
testing, when a suitable video image is not immediately available.
•Click and hold the module bar (just right of the right pointing arrow) and select
from the pop-up  menu the ‘Colour table’. When asked, name the table
‘purple’.
•A push button will appear in the window to ‘edit tables’. Click this button to
bring up the table edit window (or select ‘table edit’ from the ‘windows’ menu).
•In the table edit window, hold the <shift> key to freeze the animation and
click on the purple ball in the left hand view. The right hand view will now
display only the purple ball, the rest is black. If you misclicked, click the ‘clear’
button and try again.
•Close  the table edit window.

You have now told BigEye what objects you are interested in (i.e. the purple
ones) and what to ignore (everything not purple). The next step is to define your
midi output:

•Click on the rightmost icon in the module bar; this will bring up the object
edit section in this window. Use the topmost slider to set the ‘minimum object
size’ to something small (< 5).
• Click on the button ‘edit regions ..’ (or select ‘regions & masks’ from the
‘windows’ menu).
•In the region edit window, select the rectangle icon from the drawing
tools. With the mouse, draw a rectangle from the top left to roughly the middle
bottom of the screen, so that is covers appr. half the image.
•With this rectangle selected (coloured red) click the ‘action..’  button to
finally define the midi output.
•Make sure the ‘new’ button is pressed, and click and hold the ‘end’ pop-
up  button in the top left. Select ‘note on’ from the pop-up , leave the channel at
1, set the pitch to f.i. 60, and set the velocity to 100.
•Click the ‘move’ button at the bottom, select ‘pitch bend’ from the pop-
up , leave the channel at 1, and scroll the rightmost numerical to ‘Y’ to have the
y-position of the object determine the amount of bend.
•Click the ‘gone’ button  and here select ‘note off’, channel 1, pitch 60 and
velocity 0.
•Click ‘done’ and close the region edit window.
•Back in the channel window, select ‘show regions’ and ‘show objects’. On
your midi module select a sustaining sound (i.e. organ - like) and marvel at what
you’ve just created.
image filters

Bigeye provides five types of image filter, two of which are very important and
four which are of minor usefulness. Either of the two important ones will usually be
sufficient, the threshold filter for when you use a black and white camera and the
colour table filter for use with a colour camera. The central idea behind these
image filters is to single out those objects in a scene which are important, i.e. filter
out the things in an image that you don’t want BigEye to interpret. In the end,
when BigEye attempts to track objects, the only thing that counts is which pixels in
the image are ‘on’ and which are ‘off’. Off pixels being pixels that are absolutely
black and ‘on’ pixels holding any value other than absolutely black.  Colour or
brightness information is no longer relevant at that stage. The filters in order of
usefulness:
•colour table:
    This filter allows you to single out objects in the video image on basis of
    their colour, allowing you to look, for instance, only at the green and blue
    objects in a scene, or just at the red objects. It can also be used  to single out
    colours you don’t want to look at, where you have for instance a background of
    a particular colour (or couple of colours) that you’re not interested in, and want
    too interpret at all other colours. (see colour table edit, p ). When
    selected in the module bar you are presented with a shortcut button to the
    colour table editor, and with a pop-up  menu which allows you to select the
    current colour table.
•threshold:
    The threshold filter is used to single out objects through their brightness value,
    light hands against darker clothing and background, for instance. If you have a
    black and white camera or digitizer the threshold filter replaces the colour table
    filter as the most useful. It can be used with a color camera as well, of course.
    When selected, the threshold module shows two sliders in the edit area, one
    for the low threshold; values lower than this are forced to black, and one for
    the high threshold, which represents the highest brightness value which is not
    forced to black.
•difference:
    The difference filter gives you an instrument to pick only moving elements out
    of  an otherwise quite complex scene, independent of colour or brightness cha-
    racteristics. The filter subtracts two consecutive frames from each other and
    thus retains only the differences between the two frames, which will be the
    edges of moving objects. The reasons that this module is less useful than the
    above two is twofold; firstly, there is no continuity: when an object is
    temporarily stationary it will disappear, generating a ‘gone’ message. Second: a
    moving object always generates two ‘edges’, perpendicular to the direction of
    the motion. BigEye will see these edges as two separate objects, even though
    they are generated by only one moving object. The difference module has just
    one parameter, a threshold value, which forces to black brightness values of the
    difference below a certain value. Just slide it up and down a bit to see the effect
    it has in your application.
•mask:
    The mask filter allows you to define static regions in the image which are
    to be ignored in all subsequent processing, independent of what might be going
    on in these regions. As with the colour table module two buttons are presented
    in the module edit area; a shortcut button to the regions & masks edit window,
    and a pop-up  menu button to select the current mask screen.
•despeckle:
    This filter is useful to get rid of noise, random pixels, which the previous filters
    may let through. It blacks out clumps of pixels which are smaller than a certain
    size. In the module edit area you will see a series of radio buttons, allowing you
    to select the minimum size of a group of pixels. Below this size groups of and
    single pixels will be forced to black.
    The Windows


---------------------------------------------------------------------------------
THE CHANNEL WINDOW
---------------------------------------------------------------------------------


The channel window is the main control window for BigEye, this is where you
select and configure the various image filters, initial screen, and the object tracking
parameters. A new channel window is opened for every channel you define.
These are named by appending an ‘a’, ‘b’, etc to the name of your file (or to
‘untitled’ if you haven’t saved yet).
Several elements in the channel window are fixed, they are always there:
•the monitor view: the area where either the incoming video image, or the
    filtered image is displayed. The monitor view is also used to simulate objects in
    the testing phase, by clicking and sliding the mouse across it. This action limits you
    to one object with a fixed size, but is nevertheless very useful to test your setup
    and especially you scripts.
•the module bar: BigEye is processing the image in a series of modules, the
    output of one module is the input to the next. A module either filters the
    image, or interprets the filtered image and converts it into midi. In the module
    bar one can imagine a stream going from left to right, starting at the arrow.
    Clicking in the module bar produces a pop-up  menu allowing you to add a
    module. Clicking on a module selects it and sets up the edit area (see below) to
    edit the parameters of this module. Clicking a module and holding the mouse
    down for a while gives you the same pop-up  menu again, with the option to
    remove the module, or change it to another. One module is fixed and is always
    there: at the far right of the module bar you’ll find the objects module. This is
    not an image filter, rather it is the module which takes the previously filtered
    image and does the actual interpretation and midi generation. Its edit field will
    be discussed below.
•the view bar: this bar allows you to select what to display in the monitor view,
    and also to switch the monitor view off to save processing time. Clicking the
    view bar above any module in the module bar (see below) switches the view in
    the monitor to the video image as it looks after being processed by this filter
    module. A red bar will show in the view bar tell you what you’re looking at.
    Clicking this red bar itself switches the monitor view off. When you click the
    view bar above the arrow in the module bar you will switch the view to the
    video source image.
•channel on/off switch allows you to completely disable the processing for this
    particular channel. In a performance this function is also accessible through the
    scripts. (see channel command, p  ).
•module edit area: when one of the modules in the module bar is selected it
    sets up the top right hand area of the channel window with buttons and sliders
    to edit and adjust its parameters. See image filters (p ) for a look at the editable
    parameters of each of the filters.



With the last module in the module bar selected, and the view set to this
module (red bar above the module) you will have the best indication of how
BigEye is dealing with your settings and your image.
If you have not activated show objects the monitor image will show you the
image as it appears after the last filter. When you activate the show objects
checkbox the monitor image will show you your source image, with superimposed
on it the objects that BigEye has found. Objects are represented by a number
(the object number) and a vector. The vector gives you a graphical representa-
tion of the object’s direction and speed (longer vectors are higher speed), the
object number is available in your scripts (see also the accur parameter p .
When you activate the show regions checkbox BigEye will draw the current
screenful of regions in the monitor view. When you select another screen through
the screen command (p  ) this new screen will be drawn, although the screen
pop-up  will not show the new name.
The top button is a shortcut to the screen editor, the second button is the initial
screen pop-up .  BigEye will start with the screen selected here after an Initialize
(p  ) command.
Finally, there is the minimum object size slider which allows you to specify a
minimum object size which you are interested in; objects smaller than this size are
simply not seen by the interpreter.

---------------------------------------------------------------------------------
THE COLOUR TABLE EDITOR
---------------------------------------------------------------------------------


In the colour table editor you make the colour tables you will be using in your
performance. A colour table (one of the image filters) allows you to define which
colours should be blocked by the system and which should be allowed through for
further processing. If a colour is blocked it means that the corresponding place in
the image will be completely black and will not be analyzed by BigEye in
subsequent stages. Any combination of colours can be selected to be blocked or
to be let through and you can make different colour tables which you can later
select through software (see colour table p ) or can be used in different
channels. It is quite important to realize that the purpose of the image filters is to
significantly reduce the amount of information BigEye needs to process. A well
defined colour table should in general show, therefore, an almost black image on
the righthand side, with only spots of colour here and there.

When you make a new table it is initially cleared, none of the colours are allowed
through. You will slowly build up your table by clicking in the left image, which is
the unprocessed source image, on the objects of the colour you want BigEye to
see. As you click along you will see objects of the selected colours appear in the
right image. As the program compares 32000+ colours with the colour you click
on the response might be a bit sluggish on slower machines. To make the clicking
on moving objects a bit easier you can press the SHIFT key to temporarily freeze
the image; CAPSLOCK will also freeze the image (a bit more permanently).

Since you are usually interested in objects of a particular colour, and not in the
colour itself, and since objects in real life are very rarely precisely one colour,
BigEye accepts not only the actual colour you click on, but also colours within a
certain ‘distance’ from the target colour. This is what the bleed slider is control-
ling. The numbers don’t refer to any real quantity, a lower number means that
BigEye is looking only at a narrow range around the colour you click on; move the
slider more to the right and more and more shades will be selected with your
click.
If you move the bleed slider you may  (again, on slower machines) find it moves
in a very jerky fashion. This is because BigEye is recalculating the table for the last
colour you clicked on, with the new bleed values, as you slide.

The add and subtract radio buttons control wether the clicked colour is added
to the allowed colours or subtracted from them.
The clear button clears the table and leaves no colour selected.
Finally you have the current table pop-up  at the bottom of the window to
select which table you will be working on.

---------------------------------------------------------------------------------
REGIONS & MASKS EDIT
---------------------------------------------------------------------------------

The RegionDef window is the most complex window of the program. It is used
both to edit your screens (presets) and to edit masks.
A  screen in BigEye is a collection of regions (hot zones), together with a hierar-
chy of scripts or action lists and three parameters which control the basic
behaviour of the video interpretation. One screen is always defined, initially named
‘screen 1’, but easily renamed to something more meaningful. BigEye does not
limit the amount of screens you define, available memory does.
A mask is basically just a screenful of regions, without the associated action lists
or scripts,  used to block (or mask out) sections of the image which should not be
interpreted by BigEye.  Any screen can serve as a mask, but if you have a need
for masks you will usually make it a separate screen, not used for anything else.

At the top right of the screen is the current screen pop-up  button; clicking and
holding the mouse here produces a pop-up  menu. The ‘new..’ entry will prompt
you for a name, after which a new empty screen is created, ready for you to
draw your regions in. The ‘rename’ entry will prompt you for a name, and then
sets the name of the current screen to it. ‘Delete’ deletes, without asking, the
current screen; this action is not undoable! Below these three entries comes a list
of all currently defined screens, select any of them to change or add to that
screen.
Below the current screen pop-up  button is the action list / scripts button. In
Script mode this button is called ‘scripts’ and is simply a shortcut to the script edit
window. If you are not in script mode it will be called ‘action .. ‘ and, when clicked,
will transform the left hand side of the regions window into the action list editor for
the currently selected region. See below for more  on the action list editor.

Defining a screen begins with drawing the regions in the image using the small
collection of drawing tools provided (if you start a new screen you will first have to
choose ‘New .. ‘ from the current screen pop-up ). The drawing tools behave
basically just as in a graphics program; the coordinate help region at the top left of
the window shows you the coordinates you are drawing at, which may be useful
as a reference in writing your scripts or action lists later.

•arrow tool
    Is used for selecting drawn regions, moving selected regions and scaling a
    selected region. Selecting a region is a matter of clicking inside the region with
    the arrow tool, after which the region will be drawn in red. Regions which are
    not selected are drawn in blue. Holding the <shift> key allows you to select
    additional regions, as does ‘dragging’ the arrow across the screen. The basic
    ‘Cut’, ‘Copy’, ‘Paste’ and ‘Clear’ commands from the ‘Edit’ menu apply to the
    regions as you would expect, regions are copied including their action lists and
    scripts, so if you intend to make many similar regions it saves a lot of work to
    first draw one region, then define its scripts or action lists, and  only after that
    do you copying and pasting.
•pen tool
    The pen tool allows you to draw in freehand any shape you may desire. Click
    and hold the mouse, draw to you heart’s content, and release the mouse.
    Choose ‘Clear’ from the Edit menu and start over if you don’t like the result.
    Since the image is updated continuously drawing will not be very smooth, draw
    slowly for smooth curves. BigEye automatically connects the first and last points
    of your shape, to close it.
•rectangle tool
    Draws rectangular regions, click the top left and drag to the bottom right. Using
    the rectangle tool changes the coordinate help format to <top, left - height,
    width> format.
•row tool
    You start out just as with the rectangle tool to draw the enclosing rectangle,
    when you release the mouse, however, you are prompted for the number of
    rows you want to divide this rectangle in. Enter your desired value and BigEye
    will make you that many regions, stacked neatly inside the enclosing rectangle.
    See the comment on grids, below.
•column tool
    Works just as the row tool, the regions are defined in a column like fashion.

Although it is certainly possible to define a grid by drawing many small  square
regions all over the image, it is highly inefficient. When you consider that each
defined region has three scripts or action lists associated with it and that for every
frame and for every object BigEye has to check the object position against all these
regions, you may start to appreciate this. A far better way to define a grid is to
draw one big region covering the total size of the grid and then, using simple
arithmetic in the scripts of this region, define the grid ‘in software’. For instance, to
define an 8 by 5 grid covering the entire screen, start by drawing a rectangular
region from the top left of the screen to the bottom right. In, for instance, the
‘new-script’ of this region you would have something like:
    x = x_position / 20
    y = y_position / 24
x will now hold a value between 0 and 7 (inclusive) and y will be between 0 and
4.

Every screen in BigEye has three parameters which allow you to influence the
way in which BigEye detects and follows objects. Three sliders at the righthand
side of  this window are used to adjust these. The leftmost of these sliders,
labelled ‘accur’ is fairly obscure. the ‘accur’ stands for positional accuracy, the
higher the setting the more accurate BigEye will number the objects on screen.
Unfortunately, the higher the positional accuracy, the lower the dynamic accuracy
(hence the nickname Heisenberg slider). So, when you want your object
numbering to be very precise (once an object has acquired a number, then this
same object will retain this same number, numbers tend to jump around less)
slide the accur slider up a lot. On the other hand,  for a fast dynamic response,
when you have, for instance, assigned a different sound to an object when it has a
speed exceeding a certain threshold, you should use a lower value for thew
‘accur’ parameter. Experimentation with this slider will give you a feel for how it
behaves. In short, when you are playing a ‘drum’ use a low setting, when you are
playing violin with one hand and clarinet with the other use a high setting.

The second slider, labelled ‘perst’, controls the object persistence parameter.
Object persistence allows you to keep objects around for a while after they have
physically disappeared from the screen. BigEye calculates speed, position and
other parameters based on the speed etc. of the object before it vanished. The
object_virtual special variable is set to true and BigEye pretends the object is still
there for the specified number of frames. There are several situations where this
functionality is desirable; when two objects briefly cross paths the object count
goes from two to one to two. With a persistence parameter other than zero you
will keep the object count to two and, with a bit of luck, you will even have the
correct object numbering after the ‘collision’. In another situation you may have
masked out a small region in the image, making objects briefly disappear when the
‘fly’ across this masked out region. Again, set persistence to a couple of frames and
you have a good chance that the actual object is ‘picked up’ again after it
reappears by the virtual object. In this case the object_virtual flag is cleared and it is
as if the object never disappeared.

The third slider, labelled ‘maxob’, controls the maximum number of objects
BigEye will look for. Set to two, for instance, BigEye will cancel the object search
after it has identified two objects. It makes object numbering more accurate, and
it saves some time if you set this slider as low as your application allows.

Lastly, in this window you will find three checkboxes, labelled
‘renumber’,’numbered’ and ‘filled’. These are concerned with the order in
which BigEye will search for objects in overlapping regions. In the case an object is
detected in a region which overlaps another, scripts associated with the lowest
numbered region are executed first, successive higher numbered regions later.
The ‘filled’ checkbox makes BigEye draw the regions opaque, giving you an
easy view of which regions lie on top and which are below. Lower numbers will
appear on top of higher ones. ‘Numbered’, which is on by default, draws the
region numbers in the regions, for easy reference if you use the region numbers
in your scripts, for instance. You can switch off the region numbering if the display
gets to cluttered. If you want to change the region numbering, to match you
scripts code, or to change the order of overlapping regions, click the ‘renumber’
checkbox. After clicking the renumber button you should select the regions in the
new order, lowest numbers (topmost regions) first. After you select the regions in
this way they will turn green, and the new numbers will appear in brackets in the
regions. After you have selected the last region the renumbering will be executed.
If you want to cancel the renumbering, or want to start again because you have
made a mistake you can click the renumber button to stop the process.

---------------------------------------------------------------------------------
THE ACTION LIST EDITOR
---------------------------------------------------------------------------------

When you click on the action.. button when you have a region selected in the
region defs editor, you will be taken to the action list editor. The action lists
provide a simple interface to BigEye. The drawback is that most of the power you
have when you use the scripting interface will not be available to you. When your
needs are simple, or when you do your intelligent processing in another program
(i.e. MAX) with which you communicate through midi, the actions lists may be
sufficient.
In the action lists editor you are able to specify (midi) events in response to
objects entering, moving in, or leaving a region. The bounding rectangle of the
region you are editing is printed at the top  of the window for reference. At the
bottom of the window you will find five buttons; the new, move and gone
buttons take you to the action lists associated with the regions’ respective events,
the cancel button takes you back to the region editor without changing any of the
action lists and the done button accepts changes to the action lists and also goes
back to the region editor.
An action list consists of up to 10 midi messages which will be sent when the
corresponding event occurs. At the left you will find one to ten pop-up  menus,
where an end always signifies the end of the list. To the right of these pop-up
buttons you will find from one to four parameter buttons, which are ‘numericals’;
click the mouse on them and move (with the mouse button still down) up and
down to scroll through the list of available values. Let’s have a look at the pop-up
menus on the left, to the right of the entries you will find the meaning of the
parameters:




end:    The end of the list;
nof:        Send midi note off; channel, pitch, off velocity
non:    Send midi note on; channel pitch velocity
pkp:    midi poly key pressure; channel, key, pressure
ctl:        midi controller; channel controller number, value
pgc:    midi program change; channel, program
prs:    midi channel pressure; channel, pressure
pbd:    pitch bend; channel, low value, high value
note:    send note; channel, pitch, velocity, duration
screen:    change screen; screen name

In the numericals you will find, next to a range of numbers (0-15 for channel, 0-
127 for other midi parameters) several other selectable mnemonics. These access
attributes of the object or region which is triggering the event for use in the midi
message.
Several of these are dynamically scaled into the midi range (0-15 or 0-127,
depending on the use), sze and V are used most. Dynamical scaling is a
somewhat unsatisfactory but nevertheless useful way of getting numbers into a
specific range, even when you don’t know in advance what range the numbers
will be in. What it means is that the largest number seen so far is translated into
the maximum target value (127, for instance), and when lower numbers are seen
they are scaled accordingly. When a new, larger, source number is seen this will
then be the target 127. The upshot is that, when you start up, relatively small
numbers will be scaled to big values, until the system sees larger source numbers
and converges onto an acceptable scaling. It also means that when you will have
one freak large number, which is not normally produced, this number will redefine
the 127 and all next numbers will be scaled to values which will be too small. To
reset the dynamic scaling values (and have the system recalibrate) you can hit the
space bar at any time a channel window is frontmost. What it boils down to is
that you will have to exercise the system a bit before actual use.
(If this behaviour is unacceptable you will have to resort to scripting, where you
will have complete control over the scaling).
Here are the object attributes available:
•X and Y are the absolute coordinates of the object in the image, scaled into the
    appropriate midi range where left or top is 0 and right or bottom is 127 (or 15).
•(X) and (Y) are the coordinates relative to the region the object is in. If the
    object is at the extreme left of the region (X) will be 0; is the object at the
    extreme right of the region (X) will be 15 or 127.
•vX and vY are the component velocities: up means vY is smaller than zero,
    left means that vX will be smaller than zero. These are dynamically scaled.
•V is the velocity of the object, dynamically scaled into the midi range.
•aX and aY are the component accelerations, really the difference between the
    current and the previous component velocity.
•sze is the, dynamically scaled, size of the triggering object.
•obnm is the object number as can be seen in the channel window when you
    have the show objects check box activated.
•lon is a special one, it stands for last on and is used only with the note off
    message. When you use this the channel and the pitch information in the
    message is taken from the last not on message that was sent. This means that
    the channel information in this message can be set to anything, since it is
    discarded anyway. On notes are kept on a stack; the lon attribute uses them
    on a last in, first out basis.
•rgnm is the region number of the region containing the triggering object.


---------------------------------------------------------------------------------
THE SCRIPT EDIT WINDOW
---------------------------------------------------------------------------------

In script mode, this is the window where you write your scripts and where you
navigate between the, sometimes many, scripts. As a reminder, in a BigEye
performance you have one global script; for every screen you define you have a
start- and a stop-script, and for every region in every screen you have a new- a
move- and a gone-script. All of these scripts are accessible through this window.
The editor in this window is your basic Macintosh text editor, without much
sophistication. Cut, copy and paste all work as usual. Syntax colouring is provided
for BigEye scripting keywords (blue) and for special variables (green). Tab-size is a
fixed 4 positions, and an overall font and font size can be selected.
The righthand side of the window changes depending on the particular script you
are editing; some buttons are fixed, however. Let’s have a look at these fixed
buttons first:
•the global button always takes you to the global script, whatever you are
    editing at that moment. There is no explicit need to save the script you may be
    working on when you click a button to edit another scrip; they are saved
    automatically. Regularly selecting save from the file menu is a good idea,
    however,  but this will save the complete BigEye performance file (including all
    the scripts) you are working on.
• the p pop-up  menu on the righthand side (p for parameter) will pop up a
    menu with all the special variables you can use. Selecting any of them will insert
    it into the text, at the cursor position. This shortcut saves you typing tedious
    names and prevents typing errors.
•the screen pop-up  below the global button presents you with a pop-up
    menu of all currently defined screens, giving you access to their start-script,
    stop-script and their regions’ scripts. When you select a screen from this menu
    the righthand side of the window will show a small picture of the selected
    screen, in addition to two extra buttons (start and stop)
•the font and size pop-up  buttons allow you to selects a font and size to be
    used in the editor. These settings are global, they affect all scripts. Fonts and
    sizes cannot be mixed. The first time you select the font pop-up , on a machine
    with many fonts installed, it may take a while before it actually pops up.

When you select a screen from the screen pop-up , a start and a stop button
will appear. These will take you to the screen’s start and stop-script for editing. In
addition to these, a small picture of the selected screen will appear near the
bottom of the window. This picture is also clickable; click on any of the regions
visible in the picture to take you to this regions scripts. The region in the screen
picture will change appearance to indicate the region you are working on, and the
start and stop buttons (if they were there) will disappear to make room for three
other ones: the new the move and the gone buttons. Click these buttons to
edit the respective scripts of the selected region.
Clicking in the picture between the regions will take you back to the regions start
and stop-scripts, as will reselecting the screen from the screen pop-up  menu.


---------------------------------------------------------------------------------
DIGITIZER SETTINGS WINDOW
---------------------------------------------------------------------------------


From this window you control the video digitizer directly, and optionally select
which digitizer you will use. The different options available in the settings window
may not be available for the digitizer you are using, for instance, in the Connectix
Quickcam digitizer the only thing you can change is the brightness, the rest of the
settings have no effect. The Apple built in digitizer in the AV macs has a limited
zoom function which is accessible through the set of radio buttons in this window.
Click any of the 0.5 .. 0.9 buttons and a rectangle will appear in the image
window. This rectangle can be moved around with the mouse to position it over
the part of the image you want to zoom into. Clicking the apply button will then
effect the zoom. To experiment with other zoom factors, first click the reset
button. Contrast, brightness and saturation may or may not be available, just try.
Also, if the input source is not ntsc you may want to click around on the three
radio buttons on the right.
If you have more than one video digitizer installed in your computer a second set
of radio buttons will appear in the lower right of the window, up to a maximum of
three. These are then used to select the digitizer you want to use.
the message window

The message window is used both by the program to display messages and
possibly by you to display numbers or strings through the display command (p
). The message window is resizable; you can also change the font and -size in
which the messages are displayed.
To change the font hold the option key and click anywhere in the message
window. The first time you do this be prepared to wait a bit while BigEye is
collecting all the fonts in your system.
To change the fontsize hold the command key and click in the window.


---------------------------------------------------------------------------------
SCRIPTS
---------------------------------------------------------------------------------

When scripting mode is enabled (configuration menu) actions to be taken by
BigEye in response to specific events are specified through scripts. Scripts are
basically a series of structured commands that tell BigEye, step by step, what to do
in a specific situation. The scripting system is a programming language, and users
inexperienced in computer programming will have to invest time in order to be
able to use the BigEye scripting system to its full potential. Reading an introductory
text on computer programming may be helpful. Careful reading of this manual and
study of the provided example files will be of use to everybody.

There is one global script for system wide definitions, there are two scripts for
each defined screen and three scripts for each region in a screen.

The global script is never executed directly in response to any event in BigEye. It
typically holds code that is called from other scripts (procedures), definitions of
variables that need to be available to all other scripts, and table definitions.

The two screen scripts, called the start-script and the stop-script hold
definitions for variables which need to be available to these two scripts and to the
region scripts defined in this screen. These scripts are executed: the start-script is
executed when a screen is selected through a screen command in another script
or through the screen select pop-up  menu in the channel windows. The start-
scripts of the screens selected in the channel windows are also executed after a
successful init & run command. The stop-script  is executed whenever the screen
to which it belongs is replaced by another screen, either through a screen
command in another script or through the screen select pop-up  in the channel
window. A typical use of start-scripts is for instance to use them to send program
changes to connected synthesizers when new screens are selected.

The three region scripts are called the new-script, the move-script and the
gone-script. These scripts strictly belong to the region to which they are attached;
variables which are declared in either one of these scripts are available to all three,
but nowhere else. See variables (p  ) for a more thorough explanation of these
variable validity issues. The new-script is executed whenever an object either
materializes in the region or when an object moves into the region from the
outside. The move-script is called when an existing object, already in the region,
moves. The gone-script is called when an object previously seen in the region
either crosses the border and moves outside the region, or the object simply
disappears.

The simplest approach to programming BigEye is probably to define variables,
tables and procedures in the global script and, in the other scripts, to concentrate
on the actions to be performed. Once the concept of variables local to a region
and variables local to a screen become clear one can ‘unclutter’ the global script
by moving definitions to where they are used.
Variables

All variables in the BigEye language are floating point, that is, they can hold fractio-
nal numbers as well as integer numbers. The range of floating point numbers is
very big, although in the very big and very small the number representation will
not be exact. In the range you’ll likely be working in representation is exact.
Floating point has two main advantages over whole number representation: you
can use fractional values (i.e. 2.5, 0.2 etc) and you  avoid rounding errors when
doing calculations. BigEye will convert these floating point numbers into integers
(whole numbers) when necessary; when using midi calls for instance, or when
doing bit manipulations. Usually all this is completely transparent, you need never
explicitly convert to integer numbers. An int (p  ) function is provided, however,
for those cases where you’re interested in the integer part of a number only.
Variables do not strictly need to be defined before they are used; it is an error,
however, to use an undefined variable before any value is assigned to it (i.e. in the
righthand side of an expression). In general it is wise and much clearer to define all
variables used.
The scope of a variable is the concept of where a variable is valid in the code. If a
variable is out of scope in a certain section of the code (in a particular script in
BigEye) it means that the variable is simply not known at that point. In BigEye this is
determined through the place where the variable is declared. Variables declared in
the global script are always in scope, they are known in all scripts. Variables
declared in the start and stop-scripts of the screens are known only in these two
scripts and in all the region scripts of this particular screen. Variables declared in
the new, move and gone-scripts of a region are known only in these three scripts
and are valid for this particular region only. And lastly, variables declared in
procedure definitions or are as parameters to the procedure (p  ) are local to
the procedure, and will not be recognized anywhere outside the procedure
definition. The advantage of this rather complex arrangement is that you can
declare, for instance, a variable called current_note in a script belonging to a
certain region, and a variable with the same name in a script belonging to another
region without the two variables interfering with each other; the first
current_note is out of scope in  the second region’s scripts and will not be
confused with the current_note of the region under consideration. This means
that you can use the same name for variables with the same function in different
scripts, making for much more readable code.  Variables declared locally in
procedure definitions are not permanent, they do not retain their value across
calls to the procedure. All other variables are permanent. In scheduled code (p
) you should use only globally declared variables, or (fleeting) variables declared
locally in the scheduled procedure’s definition. See smooth p  for a way to filter
variable values.

---------------------------------------------------------------------------------
PREDEFINED VARIABLES
---------------------------------------------------------------------------------

A series of special variables is predefined, and will hold values relevant to the ob-
ject which is causing the script to be executed, the region to which the script is
attached, and some global information which might be useful in a specific context.
These variables are all strictly read only, attempts to write to these variables will
result in an error message. The contents of these variables is not defined in code
which is executed through the scheduler; when these values are needed in sche-
duled code you can either pass it to the code to be scheduled as a parameter or
copy the value into a normal variable which is then read by the scheduled code.

•x_position
    The x_coördinate of the absolute position of the current object, (0  to 159).

•y_position
    The y_coördinate of the absolute position of the current object, (0  to 119).

•object_size
    This variable holds the size (in arbitrary units) of the current object, one of the
    more powerful variables, giving you a virtual third dimension (moving toward
    and away from the camera will change the object size). The object size can
    take (floating point) values from 0 to about 130 (which would cover the whole
    screen).

•object_speed
    The speed of the current object (in pixels per frame), the number of pixel
    positions between the previous and current position of the object.

•object_direction
    The direction of the current object. North is zero, east is 1.57 (pi / 2), south is
    3.14, west is 4.71 and a few degrees west of north is almost pi * 2 :). Of
    course you will get intermediate values for intermediate directions.

•x_speed
    The speed in the x_direction, in pixels per frame. Can be negative as well as
    positive; negative values indicate movement to the left, positive values mean the
    object is moving to the right.

•y_speed
    The speed in the y_direction, in pixels per frame. Can be negative as well as
    positive; negative values indicate movement up, positive values mean the object
    is moving down.

•channel_number
    The channel_number special variable is set to the channel number of the current
    channel, the channel which caused the script in which the variable is used to be
    executed. Channel ‘a’ is given channel number 0 (zero), channel ‘b’ will be 1
    (one) etc.

•current_tick
    The current_tick variable holds the interrupt schedulers’ tick count; the schedu-
    ler is called every 5 milliseconds, so the value of current_tick is the number of 5
    ms ticks since the last initialize & run (command I). See also scheduler, p

•object_count
    Holds the number of objects active in the current frame, anywhere from one
    (zero objects would never cause the script in which this variable is used to be
    triggered) to 16.

•object_number
    The number assigned by BigEye to the current object, corresponding to the
    those one sees in monitor mode and in the object edit screen, with the show
    button selected. These numbers are fleeting, BigEye tries its best to keep the
    same object number assigned to an object throughout its life, but sometimes
    fails to do so properly. In the screen editor one can adjust several parameters
    which affect the assignment of numbers to the objects. See regions & masks
    edit, p

•object_virtual
    This variable holds only two values, zero and non-zero (false and true). It re-
    flects the state of the object, is it an actual physical object, or is it an object
    made up by BigEye for continuity. See persistence (p  )

•region_max_x
    This variable holds the maximum x coordinate of the region to which the
    current script is attached. (0 to 159) See scaling coordinates (p  )

•region_max_y
    The maximum y-coordinate of the current region. (0 to 119)

•region_min_x
    The minimum x_coördinate of the current region.

•region_min_y
    The minimum y-coordinate of the current region.

•region_number
    The number of the current region, as visible in the region edit screen with the
    numbered button selected.

•object_acceleration
    This variable holds the acceleration of the object triggering the current script, it
    is simply the difference in speed of the object between the previous frame and
    the current frame.

•x_acceleration
    See object acceleration, in this case the difference between the x_speed of two
    consecutive frames.

•y_acceleration
    See object acceleration, in this case the difference between the y_speed of two
    consecutive frames.


---------------------------------------------------------------------------------
Expressions
---------------------------------------------------------------------------------

In the following descriptions of the BigEye scripting language you will very often
come across the word expr; this is short for ‘expression’ and can be:

•a number, which can be either ordinary decimal 1, 2.6, -765.23, etc,  or hexa-
    decimal: $1, $2, $15, $77, etc. One can also use character literals of the form
    ‘a’ or ‘7’; note the apostrophes, they are part of the syntax. These character
    literals are immediately converted into their ascii number equivalent and act just
    as numbers. So ‘A’ and 65 are identical ‘numbers’ as far as BigEye is concerned.
    All numbers are floating point and are automatically converted to integers
    (whole numbers) when necessary (midi, bit operations).
•an identifier, i.e. a variable name or one of the special variables to be discussed
    below.
•a function call.
•Any combination of the above strung together with any of the following
    operators:
    Operators are given in order of precedence, i.e. if you see something like 'a +
    b * c', 'b*c' will be evaluated first, then ‘ a + ‘. In this case one says that the '*'
    operator takes precedence over the '+' operator. In the table below operators
    with the highest precedence are given first. Operators in the same section have
    equal precedence and are 'left binding'. Left binding means 'a * b / c'  will be
    evaluated as (a*b) / c; i.e. is evaluated from the left. Some of the operators are
    denoted as boolean. This means is that they will only have two distinct values,
    true and false. Typically they are used in 'if' statements, their actual values are 0
    for false and -1 for true, although in a boolean context (in an if statement for
    example) any value other than 0 will be treated as true and can be used as a
    boolean;
    var a = 20; if(a) { do something }
    is legal and often very useful;

(...)
    Parens group subexpressions, and are used to force a different order of
    precedence as needed; ' (a+b)*c ' makes sure the addition is performed
    before the multiplication.

The following four operators are 'unary', they only affect the subexpression
immediately to the right of them.

!
    Logical negation, if the subexpression immediately to the right evaluates to
    true, it would be changed to false, and vice versa. For example:

    if(!object_virtual) {
        note(0,y_position, object_speed * 2,100)
        sent = true
    }

~
    bitwise negation; the expression to the right of the ~ is evaluated,
    converted into a (32 bit) integer and then every bit in this integer will be flipped.

-
    negates the subexpression to the right, 1 becomes -1; -20 becomes 20
    etc.

The following five are the regular arithmetical operators, they behave just as
expected.

expr / expr
    divide
expr % expr
    take modulus (remainder after (integer)division)
expr * expr
    multiply
expr + expr
    addition
expr - expr
    subtraction

The next three are bit operators, these operators work on the bit level and are
useful to mask out midi channels and such things. Bit manipulation needs a working
knowledge of the binary representation of numbers in a computer. Numbers are
converted to integers before any of these operations are carried out.

expr & expr
    bitwise and
expr | expr
    bitwise or
expr ^ expr
    bitwise exclusive or

channel = channel & 15;

forces the variable channel into the range 0 - 15. Be aware that we’re talking
about bitmanipulation; myVar = myVar & 16; will not force myVar to be in the
range 0 - 16, rather, it will set it to either 16 or zero, depending on its previous
value.
The ‘exclusive or’ operator is very convenient to ‘toggle’ the state of a boolean
variable:

    var sustain = 0        // declaration of ‘sustain’
    sustain = sustain ^ 127    // 127 becomes 0 and
                        // 0 becomes 127
    ctr(0,64,sustain)
    end

This small program will alternate between switching sustain on midi channel one
on and off.

The next two are also operators on the bit level;   ‘ a >> b’ shifts ‘a’  ‘b’ places
to the right.

expr >> expr
    shift right
expr << expr
    shift left


The remaining operators are all boolean, they evaluate to a true or false, a -1 or
a 0.

expr > expr
    greater than
expr < expr
    smaller than
expr >= expr
    greater than or equal to
expr <= expr
    smaller than or equal to
expr == expr
    equal
expr != expr
    not equal

expr1 && expr2
    logical and
expr1 || expr2
    logical or

The last two operators  leave a true if both expr1 and expr2 are true or in the
or case if either expr1 or expr2 is true.

Lets give just one example for the last bunch:

    if( a && distance > 150 && ( pressure <= 10 || always == true))
     a = false;

will set a to false when a is true, distance is bigger then 150 and either
pressure is smaller than or equal to 10 or always is nonzero.

In order of precedence:

( )
! ~ -
* / %
+ -
& | ^
>> <<
>< >=<= == !=
&& ||




---------------------------------------------------------------------------------
BIGEYE SCRIPTING KEYWORDS
---------------------------------------------------------------------------------

abs(expr)
    abs evaluates its parameter and returns the absolute value of the result; if expr
    evaluates to a negative number abs chops off the minus sign, otherwise it just
    returns the result of the evaluated expr.

channel(expr1,expr2)
    the channel command provides a way to switch different channels on and off.
    The first expression should evaluate to a channel number (0 for channel ‘a’, 1
    for channel ‘b’, etc); the second expression is interpreted as a boolean value
    (true or false) and is used to either make the channel in expr1 active or make it
    make it inactive.  Returns nothing.

colortab “table name”
    sets the current channels’ colour table to the table “table name”, if it exists. If
    not, or if colour tables are not used in the current channels’ image filters,
    nothing happens.  Returns nothing.

display(“string”)
    displays the string in the message window. See message window (p  ).

display(expr)
    evaluates the expression and displays the result in the message window. See
    message window (p  ).

end
    end is the statement which terminates execution of a script, and signals BigEye
    to stop executing the current sequence of code and check the next object,
    region or whatever.

false
true
    these are numeric constants, internally to the program they are equivalent to 0
    (false) and non-zero (true). They are mainly used to improve the readability of
    pieces of code, for instance in an if statement.

if(expr)
else
if (expr)   <comp-stmnt1>
if (expr)  <comp-stmnt1>  else  <comp-stmnt2>

    Conditional execution; <comp-stmnt> here means any one statement or a
    series of statements between braces '{' and '}'. If the expression evaluates to a
    non-zero value (to true) comp_stmnt1 will be executed, if it is false (zero)
    comp-stmnt2 will be executed.

int(expr)
    converts any expression into an integer value, that is, the fractional part of the
    expression is simply chopped off, no rounding is performed. Normally you will
    not need to use this call, because BigEye will automatically perform this
    operation when necessary. When testing the equality of the integer part of two
    numbers, however, it may be very useful;

actsense()
    actsense sends a midi active sensing message ($FE, 254); generally not of much
    use, but it can, with most synthesizers, be very effective as an all notes off
    command.

ctr(expr1,expr2,expr3)
    sends a midi controller message, expr1 will be automatically limited to a number
    between 0 and 15 (for midi channel), expr2 and 3 are limited to 0 to 127.

mfstart(ident,expr)
    Starts playing a midi file sequence, ident is a name you will be using to refer to
    this particular midi file. Expr is evaluated and, if it is non zero, the sequence will
    be started in ‘loop mode’, when the sequence is at the end, it will loop and
    start again. When expr evaluates to zero the sequence is started and played
    only once. BigEye will ask you for the actual midi file you are referring to using
    ident at compile time (with an Initialize - p   - command).

mfstop(ident)
    Stops playback of the sequence ident.

mfstatus(ident)
    This command is only used in expressions, and returns a one if the sequence is
    still playing, or a zero if the sequence has finished.

if(!mfstatus(riff)) mfstart(riff,0)

    is used, for instance,  to make sure you don’t start two copies of the same
    sequence playing at the same time.

mftempo(ident,expr)
    This command allows you to dynamically change the tempo of playback of the
    sequence ident. A tempo of one is normal speed, as defined in the midi file the
    sequence was loaded from, 2 is twice normal speed and 0.5 is half speed.

midicont()
    Midi continue message.

midireset()
    Midi reset message ($FF)

midistart()
    Midi start message.

midistop()
    Midi stop message.

nof(expr1,expr2,expr3)
    Midi note off command, sends an actual note off command (as opposed to a
    note on command with zero velocity). expr1 is the channel, expr2 the note
    number and expr3 the off velocity.

non(expr1,expr2,expr3)
    Mid note on command, expr1 is the channel, expr2 the note number and
    expr3 the velocity. This command does not send any note off command, see
    the note command for this.

note(expr1,expr2,expr3,expr4)
    Midi note command, expr1 is the channel, expr2 the note number expr3 the
    velocity and expr4 is the duration of the note. After this duration (in 5
    millisecond units) BigEye sends a matching note off command.

pbd(expr1,expr2,expr3)
    Midi pitch bend message, expr1 is the midi channel, expr2 is the least significant
    7 bits of the bend, expr2 the most significant 7 bits. Generally expr2 is irrelevant
    and set to 64; expr3 is the actual bend value (64 no bend, 0 down all the way
    and 127 is up all the way).

pgc(expr1,expr2)
    Midi program change. expr1 is midi channel, expr2 is the actual program to be
    selected.

pkp(expr1,expr2,expr3)
    Midi key pressure command; expr1 is midi channel, expr2 is the key number
    and expr3 is the pressure value.

prs(expr1,expr2)
    Midi channel pressure, expr1 is midi channel and expr2 is the pressure value.

songpos(expr1,expr2)
    Midi song position select, expr1 is the least significant 7 bits, expr2 the most
    significant 7.

songsel(expr)
    Midi song select, expr is the song number.

sysex(expr, ...)
    Midi sysex (actually just raw midi); for sysex you have to provide the header
    ($F0) and the end ($F7). The comma separated list of expressions are - one by
    one - evaluated and send out the midi port without any interpretation.

timeclc(expr1)
    Midi timeclock.
timecode()
    Midi time code.

tunerec(expr)
    Midi tune request; expr is tune number.

proc(p1,p2)
    Starts a procedure definition; p1 and p2 are optional parameters to the
    procedure. See procedures (p  ).

endproc
    closes the definition of a procedure, this is where a procedure stops executing
    when called from elsewhere. Also, after an endproc, variable declarations will
    stop generating local variables . See procedures (p  ) and variables (p  ).

random(expr)
    Evaluates the expr and then returns a random number in the range [0 - expr).
    See also rseed.

rseed(expr);
    The rseed command primes the random generator, to get a sequence of ran-
    dom numbers several times (that is: the same sequence) use rseed with the
    same  value; what this value is not important, it only matters that the value is
    the same as the last time.

schedule(expr,proc,p1,p2)
    schedules a procedure to execute at a future time. expr is evaluated, and is in-
    terpreted in 5 millisecond units, (so 200 will be one second). proc is the name of
    the procedure (see procedures, p  ) to be executed expr times 5 ms in the
    future. If the procedure takes parameters, p1 and p2 will be used as such. If
    the procedure just takes one parameter you can leave out p2 from the
    schedule statement, if the procedure takes no parameters at all leave out both
    p1 and p2. Scheduled procedures execute under interrupt, please read the
    relevant section of the manual (p ).

screen “new screen”, expr
    will swap the current screen of channel expr to the screen “new screen”. If the
    old screen has a stop-script, this will be executed prior to the swap. If the “new
    screen” has a start-script, this script will be executed after the swap.

smooth <ident>,<number>
    This command defines a ‘smoother’, with name ‘ident’. The <number> defines
    the length of the ‘smoother’, larger numbers smooth more. The smoother in
    fact just returns the average of the last <number> of uses of the smoother.
    You use the smoother by calling the <ident> as if it were a procedure (p )
    with one parameter. It returns the smoothed value.

    smooth direction_smoother,10// declaration


    // and the use it like this:
    direction = direction_smoother(object_direction)

    to have the variable direction be the average of the last 10 object_directions.
    Accepted values for the <number> are from 2 to 100.

table <identifier>  [<numeric>,(<numeric>, ... )];

table convert [1,3.14,5,7,9,11,13,15,17,19,21,23,25];
table convert [lin,256,0,127];
table convert [ 1.0,2.4,3.14,4,5,6,7,8,9,ran,20,1,3,22];

    Tables are data structures in memory consisting of a predefined number of
    consecutive variables.  The length of these tables is fixed when they are defined
    and cannot be altered dynamically. The examples initialize the tables. In cases
    where you don’t need something specific in the table at the start, as in defining
    a buffer for storing values, use a lin,256,0,0 (for a table with 256 entries).  To
    access an element in a table you use an offset between square brackets, no
    bounds checking is performed, you should see to it that you don’t address
    anything beyond the defined length of the table, you may be overwriting other
    tables or worse. Negative offsets are allowed, if you can find a use for them.

    <numeric> in the syntax definition stands for one of five things:
    •A simple number, decimal or hexadecimal ($ - prefix, integer only)
    •a lin keyword; this word stands for linear and defines a linear stretch of
        numbers. It takes the next three numbers as parameters, first a length, then a
        start value and lastly an end value:
    lin,256,0,127
    defines 256 bytes of which the first is a 0, the last is a 127 and the
    254 bytes between these two run linearly between these two.

    •a ran keyword; this word stands for random and defines a random stretch
        of numbers. It takes the next three numbers as parameters, first a length, then
        a minimum value and lastly a maximum value;
    ran,20,10,30
    defines 20 random bytes, never lower than 10 and never higher than 30.

var <identifier> ( = <number)(, <identifier> ( = number), ...)

var a;
var x,y,z;
var sustain = false;
var breath = 2, modulation = 1, pan = 10;

    This keyword defines a basic variable (floating point, range ± 1.17549e-38 to
    3.40282e38) , it can later be referred to by its name (the identifier). The
    optional initialization can set the value the variable starts out with, after
    initialisation (command I).

while(expr)   <comp-stmnt1>

    Executes  <comp-stmnt1>  (see above under if)  repeatedly until expr be-
    comes false. This implies that somewhere in <comp-stmnt1> something
    should happen that influences the expr, otherwise you would end up with a
    loop which would never exit and BigEye would never execute anything else
    until a reset (it would ‘hang’).

---------------------------------------------------------------------------------
PROCEDURES
---------------------------------------------------------------------------------

When you have a section of code that you want to use in a variety of places, you
may be tempted to copy the relevant code to wherever you will be using it. This
would be a mistake. A procedure is  a piece of code that you can call from all
scripts in BigEye, but write only once. A procedure can simply execute some
code, or can do a specific calculation and return the result to the calling code.
An example of the first kind if a procedure which steps through a number of
defined screens:

var CurrentScreen=0;            // define a var to keep
                            // track of where we are
proc StepScreen()                // start proc definition
    if(CurrentScreen == 0) {        // if we are at 0
        CurrentScreen = 1
        screen “screen 1”,0    // swap to 1
    }
    else if(CurrentScreen == 1) {
        CurrentScreen = 2
        screen “screen 2”,0
    }
    else {
        CurrentScreen = 0
        screen “screen 0”,0
    }
endproc                        // end of procedure def

As an example of the calculating kind of procedure, here is one that scales the x
coordinate into the (midi) 0 to 127 range, relative to the region the object is in:

proc scaleX()
    var x,regionwidth;
    regionwidth = region_max_x - region_min_x
    x = x_position - region_min_x
    scaleX = (x * 127) / regionwidth
endproc

As you can see to return a value from a procedure you end the procedure
with an assignment to the procedure name, as if it was a variable. This proc will
return a zero when the object which caused this proc to be called is at the
extreme left of the region, and a 127 when the object is at the extreme right.
Many times you will want to use the same code to calculate something, but with
different numbers. Procedures therefore can take up to two parameters.
Parameters are ‘given’ to the procedure by including them in the brackets when
calling the procedure. In the procedure definition you will of course have to make
clear that this is a propcedure that takes parameters by including two ‘names’ in
the definitions’ brackets. These names will then act as variables in the body of the
procedure. In the above example, if you want to scale the x_position  value into
another range than the 0 to 127 range:

proc scaleX(min,max)
    var x,regionwidth, targetwidth
    regionwidth = region_max_x - region_min_x
    targetwidth = max - min;
    x = x_position - region_min_x
    scaleX = min + (x * targetwidth) / regionwidth
endproc

When called for instance as follows:

tempvar = scaleX(30,70)

this proc will return 30 when the object which caused this proc to be called is at
the extreme left of the region, and 70 when the object is at the extreme right.
The parameters min and max in the above example are variable and can be used
as such within the body of the procedure. Outside the procedure, however the
will not be known anywhere.
A last example which just takes one parameter:

proc cube(value)
    cube = value * value * value
endproc

---------------------------------------------------------------------------------
THE SCHEDULER
---------------------------------------------------------------------------------

BigEye provides a real time scheduler to play midi files and to schedule note off
events when you use a note event. If you are in script mode you will also have
direct acces to this scheduler, giving you the opportunity to schedule procedures to
be executed at a certain, specified time in the future, with a five ms resolution.
Since the code you specify to be scheduled will be executed at the computer
interrupt level it is sure to be executed on time, the scheduler can therefore be
used to generate musical sequences with sufficient temporal accuracy. Since your
code will be executed at the interrupt level it will be extremely important that your
code is short and correct; it will be extremely easy for you to crash the whole
computer.
Since your scripts may or may not be executing at the time that your scheduled
code ‘fires’, and, if your scripts are executing, there is no way to tell where in the
scripts the computer is at that time, you cannot use the predefined variables at
all in scheduled code. From the standpoint of that code they would just contain
garbage. If you do need to use them in scheduled code there are two options
available: you can copy them into a global variable (a variable defined in the global
script) prior to scheduling your code (and also while you have a scheduled loop
running). Also, you can pass them to your scheduled routine as parameters (only
two, though). See the schedule command p  .
Since a scheduled routine can re- schedule itself it is fairly easy to make a
scheduled loop:

proc EverySecond()
    // do something useful here //
    schedule(200,EverySecond)
endproc

Once called from somewhere (maybe the startscript of the first screen of
channel a) this routine will be running every second. To stop a routine like this
from running hit the space bar whenever you have a channel window frontmost.
Since you can pass parameters to scheduled routines an easy next step, for
instance, is to program a ‘bouncing’ note:

proc Bounce(time)
    note(0,60,100,50)
    if(time > 10) schedule(time,Bounce,time * 0.9)
endproc

The time parameter will decrease with every call, eventually getting smaller than
10 to stop the scheduling process altogether. You will call Bounce(200), for
instance, from anywhere in your code to set one off. There is, by the way,
nothing to stop you from scheduling the same routine multiple times; you can have
several of these ‘bouncing notes’ going at the same time.
A simple rhythm structure can be made with the help of a table:

table delays[100,50,50,100,50,50,50,50]
proc rhythm(index)
    note(9,60,100,50)
    if(index > 7) index = 0
    if(flag) schedule(delays[index],rhythm,index+1)
endproc

Here you would start the loop by setting flag = 1 and then calling rythm(0)
in response to some event. To stop the loop you simply set flag = 0.

---------------------------------------------------------------------------------
THE MENUS
---------------------------------------------------------------------------------

FILE

•new
    Will check if you want to save your current work, after this will present you
    with a new, fresh and empty performance called Untitled.
•open
    You are presented with an open dialog box,  showing you text files, table files,
    screen files and BigEye performance files. The first three can be appended to
    the existing tables, screens or scripts or can replace them (you will be asked). If
    you open a performance file, you will first be asked to save your current work.
    Opening a text file will enter all of the contents of this file into the ‘global’ scripts.
    From there you can copy it around if necessary.
•close
    Will close the front window, nothing will be lost, the window can always be
    opened again.
•save
    Saves the current performance to disk, under it’s own name. If you haven’t
    saved yet (if the name is ‘Untitled’) you will be presented with a standard save
    dialog box.
•save as
    Saves the performance under a new name, or in a different place. You will get
    the standard save file dialog.
•save colour tables
    Allows you to separately save the colour tables to a file, which you may later
    read into a different performance and append to you colour tables there, or
    just read them in to replace any colour tables you may already have made
    there.
•save screens
    Like the colour tables, you can save your screens (including any scripts) to a
    separate screens file.
•save scripts
    This command will save all you scripts into one (1) text file, first the global scripts
    and the all the screens with their start, stop and region scripts.
•page setup
    Standard page setup dialog for printing.
•print
    not implemented yet
•quit
    If you’ve made any changes you will be prompted to save your work.


EDIT


•undo
    This command only  works in the script editor, and undoes the last destructive
    command, like clear or paste. There is only one undo, and no ‘redo’.
•cut
    Standard Macintosh cut operation, in the script editor it copies the selected text
    to the clipboard, then deletes it; in the screen editor it copies the selected
    regions, including their scripts, to the clipboard before deleting them.
•copy
    Copies selected text (in scripts editor) or selected regions with their scripts to
    the clipboard.
•paste
    Pastes the contents of the clipboard (if any) into either the current script in the
    script editor, or, if you are in the region editor and there are regions on the
    clipboard, into the current screen.
•clear
    Clears selected text or selected regions from you file. Clearing regions is not
    undoable!
•select all
    Selects all text if you are in the script editor, all regions if you are in the screen
    editor.
•preferences
    Most of BigEye’s preferences are saved automatically when you quit the
    program (things like font, window position, etc). You will therefore probably not
    need to use the preferences dialog much. The one thing in the preferences
    dialog you are most likely to need is the initialize on load checkbox. This,
    when active, makes BigEye perform an initialize command on the file it just
    loaded, allowing you to put a BigEye performance file in the system startup
    folder so that when the computer starts up the performance will run automati-
    cally.
    The next one you may need to adjust is the midi file buffer. When you are
    using midi files and perform an Initialize BigEye will load and preprocess the
    midi files you will be using. For this operation BigEye needs a buffer in memory.
    With big midi files this buffer may not be large enough in the default setting, you
    will get the message ‘midi file too big’. When this happens you can adjust the
    size of this buffer in the preferences dialog. You will have to restart BigEye and
    reload you performance after changing this value.
    The other three parameters, variable space, code space and table space
    will most likely be enough in the default setting. When you get a message ‘Out
    of code space’, ‘Out of variable space’ or ‘Out of table space’ you can adjust
    the values here. These parameters are concerned with the internal BigEye
    buffer for processing scripts. The one most likely to cause trouble  is the table
    space parameter when you are using really big tables. You will find the space
    used in your current file by issuing an Initialize and checking the values
    between braces, after the numbers. Again, restart BigEye and reload your
    performance to effect the changes.

SOURCE

•movie
    You will be presented with a standard open dialog to open a Quicktime movie
    file. This movie will from then on loop and be routed to the video processing
    software of BigEye. Everything will act exactly as if it was live video input, except
    the difference module. Since on most machines BigEye processes movie
    frames faster than the actual frame update rate from the Quicktime file, BigEye
    grabs the same frame more than once. For most modules this is no problem,
    but the difference between to frames which are equal is zero. Therefore you
    will need Quicktime movies with a very high frame rate (about 30 fps on a 7100
    / 66) or forsake the use of the difference module.
•video
    Selects the video digitizer as input. If you have no video digitizer in your system
    this item will be disabled. If you have multiple digitizers use the digitizer settings
    window (p  ) to select which digitizer you will use.
•animation
    Selects a simple animation of four coloured balls as an input to the analysis
    software. Useful for testing purposes only.


WINDOWS

•table edit
    Opens or activates the colour table edit window.
•regions & masks
    Opens or selects the screen edit window.
•digitizer settings
    Opens or selects the digitizer settings window.
•script edit
    Opens or selects the script edit window. You will have to be in script mode to
    have this item enabled.
•new channel
    Opens a new channel (if you don’t have sixteen channels open already) channel
    keyboard shortcuts are command - one through command - zero for the first
    ten channels. Closing a channel window does not delete it, it just hides the
    window. When you want to delete a channel hold the option key down
    while closing the channels’ window. You will be asked to confirm.
•channel a, ...
    Depending on how many channels you have opened you will find a number of
    menu entries here to open their window or bring them to the front.


CONFIGURATION

•mirror input
    For people who have trouble working with an image which is not mirrored; at a
    slight cost in processing time you can swap left and right before any processing.
    This setting is stored in the performance file.
•script mode
    To activate script mode for a particular performance.
•mute midi
    Mutes all midi output.
•monitor
    Toggles the monitor view on and off.
    In an actual performance the small monitor in the channel window is often too
    small to be of much use from a larger distance. To alleviate this problem BigEye
    provides a (big) monitor window. It only works, however, with channel a.
    When you choose monitor from the configuration the whole screen is taken
    over by a big, black window. In this window you will see the regions of the
    screen you are currently in, and moving around in this window you will see one
    or more numbers. These numbers are the actual objects BigEye is seeing at
    that moment, they change size according to the size of the object they
    represent. If you are not so much concerned with speed the monitor window
    offers you two more views. The view in the channel a monitor window can be
    stretched across the whole monitor by hitting (when you have activated the
    monitor window) tab once. This slows down performance to a great extend.
    Hitting tab again produces a smaller version of your channel monitor view, a bit
    faster, but still costing a lot of speed. Hitting tab again brings you back into the
    big, black monitor view. The only way out of the monitor view is by hitting the
    command-M keyboard shortcut again to deactivate the monitor.
    When you have a second monitor attached to your computer the monitor
    window will be displayed on this one, leaving you access to your other win-
    dows. The channel monitor view will not be active, however, as long as you
    have the monitor view up.
•initialize & run
    Whenever you have edited one of your scripts you will need to recompile
    them. This is (among other things) what Initialize does. It will also run the code
    in the startscripts of the screens you have selected in all used channels. When
    you hold the option key while choosing Initialize you will zap the midi file
    references. Normally BigEye will remember which midi files you are using
    after it has asked you for them once, this option allows you make BigEye forget
    about those files and forces BigEye to ask you for them again.
-------------------------------------------------------------------------------

    STEIM FOUNDATION
    HTTP://www.xs4all.nl/~steim